home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 July: Mac OS SDK / Dev.CD Jul 00 SDK2.toast / Development Kits / Cross Platform / QuickTime 4.1.2 Windows SDK / CIncludes / CoreFoundation / CFURL.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-04-12  |  10.8 KB  |  274 lines  |  [TEXT/R*ch]
  1. /*
  2.      File:        CFURL.h
  3.  
  4.      Contains:    CoreFoundation urls
  5.  
  6.      Version:    Technology:    Mac OS X
  7.                  Release:    QuickTime 4.1
  8.  
  9.      Copyright:    (c) 1999 by Apple Computer, Inc., all rights reserved
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __COREFOUNDATION_CFURL__
  18. #define __COREFOUNDATION_CFURL__
  19.  
  20. #ifndef __COREFOUNDATION_CFBASE__
  21.     #include <CoreFoundation\CFBase.h>
  22. #endif
  23.  
  24. #ifndef __COREFOUNDATION_CFDATA__
  25.     #include <CoreFoundation\CFData.h>
  26. #endif
  27.  
  28. #ifndef __COREFOUNDATION_CFSTRING__
  29.     #include <CoreFoundation\CFString.h>
  30. #endif
  31.  
  32.  
  33.  
  34.  
  35. #if PRAGMA_ONCE
  36. #pragma once
  37. #endif
  38.  
  39. #ifdef __cplusplus
  40. extern "C" {
  41. #endif
  42.  
  43. #if PRAGMA_IMPORT
  44. #pragma import on
  45. #endif
  46.  
  47. #if PRAGMA_STRUCT_ALIGN
  48.     #pragma options align=mac68k
  49. #elif PRAGMA_STRUCT_PACKPUSH
  50.     #pragma pack(push, 2)
  51. #elif PRAGMA_STRUCT_PACK
  52.     #pragma pack(2)
  53. #endif
  54.  
  55. #if PRAGMA_ENUM_ALWAYSINT
  56.     #pragma enumsalwaysint on
  57. #elif PRAGMA_ENUM_OPTIONS
  58.     #pragma option enum=int
  59. #elif PRAGMA_ENUM_PACK
  60.     #if __option(pack_enums)
  61.         #define PRAGMA_ENUM_PACK__COREFOUNDATION_CFURL__
  62.     #endif
  63.     #pragma options(!pack_enums)
  64. #endif
  65.  
  66. typedef UInt32                             CFURLPathStyle;
  67. enum {
  68.     kCFURLPOSIXPathStyle        = 0,
  69.     kCFURLHFSPathStyle            = 1,
  70.     kCFURLWindowsPathStyle        = 2
  71. };
  72.  
  73. typedef struct __CFURL * CFURLRef;
  74. EXTERN_API_C( CFTypeID )
  75. CFURLGetTypeID                    (void);
  76.  
  77. /* encoding will be used both to interpret the bytes of URLBytes, and to */
  78. /* interpret any percent-escapes within the bytes. */
  79. EXTERN_API_C( CFURLRef )
  80. CFURLCreateWithBytes            (CFAllocatorRef         allocator,
  81.                                  const UInt8 *            URLBytes,
  82.                                  CFIndex                 length,
  83.                                  CFStringEncoding         encoding,
  84.                                  CFURLRef                 baseURL);
  85.  
  86. /* Escapes any character that is not 7-bit ASCII with the byte-code */
  87. /* for the given encoding.  If escapeWhitespace is true, whitespace */
  88. /* characters (' ', '\t', '\r', '\n') will be escaped also (desirable */
  89. /* if embedding the URL into a larger text stream like HTML) */
  90. EXTERN_API_C( CFDataRef )
  91. CFURLCreateData                    (CFAllocatorRef         allocator,
  92.                                  CFURLRef                 url,
  93.                                  CFStringEncoding         encoding,
  94.                                  Boolean                 escapeWhitespace);
  95.  
  96. /* Any escape sequences in URLString will be interpreted via UTF-8. */
  97. EXTERN_API_C( CFURLRef )
  98. CFURLCreateWithString            (CFAllocatorRef         allocator,
  99.                                  CFStringRef             URLString,
  100.                                  CFURLRef                 baseURL);
  101.  
  102. /* filePath should be the URL's path expressed as a path of the type */
  103. /* fsType.  If filePath is not absolute, the resulting URL will be */
  104. /* considered relative to the current working directory (evaluated */
  105. /* at creation time).  isDirectory determines whether filePath is */
  106. /* treated as a directory path when resolving against relative path */
  107. /* components */
  108. EXTERN_API_C( CFURLRef )
  109. CFURLCreateWithFileSystemPath    (CFAllocatorRef         allocator,
  110.                                  CFStringRef             filePath,
  111.                                  CFURLPathStyle         pathStyle,
  112.                                  Boolean                 isDirectory);
  113.  
  114. /* Returns the URL's path in a form suitable for file system use. */
  115. /* The path has been fully processed for the file system type requested */
  116. /* by fsType.  If resolveAgainstBase is TRUE, then the URL's path is first */
  117. /* resolved against that of its base URL (if a base URL exists) before being returned. */
  118. EXTERN_API_C( CFStringRef )
  119. CFURLCreateStringWithFileSystemPath (CFAllocatorRef     allocator,
  120.                                  CFURLRef                 anURL,
  121.                                  CFURLPathStyle         pathStyle,
  122.                                  Boolean                 resolveAgainstBase);
  123.  
  124. /* Creates a new URL by resolving the relative portion of relativeURL against its base. */
  125. EXTERN_API_C( CFURLRef )
  126. CFURLCopyAbsoluteURL            (CFURLRef                 relativeURL);
  127.  
  128. /* Returns the URL's string. */
  129. EXTERN_API_C( CFStringRef )
  130. CFURLGetString                    (CFURLRef                 anURL);
  131.  
  132. /* Returns the base URL if it exists */
  133. EXTERN_API_C( CFURLRef )
  134. CFURLGetBaseURL                    (CFURLRef                 anURL);
  135.  
  136. /* All URLs can be broken into two pieces - the scheme (preceding the first colon) and the resource */
  137. /* specifier (following the first colon).  Most URLs are also "standard" URLs conforming to RFC 1808 */
  138. /* (available from www.w3c.org).  This category includes URLs of the file, http, https, and ftp */
  139. /* schemes, to name a few.  Standard URLs start the resource specifier with two slashes ("//"), and */
  140. /* can be broken into 4 distinct pieces - the scheme, the net location, the path, and further */
  141. /* resource specifiers (typically an optional parameter, query, and/or fragment).  The net location */
  142. /* appears immediately following the two slashes and goes up to the next slash; it's format is */
  143. /* scheme-specific, but is usually composed of some or all of a username, password, host name, and */
  144. /* port.  The path is a series of path components separated by slashes; if the net location is */
  145. /* present, the path always begins with a slash.  Standard URLs can be relative to another URL, in */
  146. /* which case at least the scheme and possibly other pieces as well come from the base URL (see RFC */
  147. /* 1808 for precise details when resolving a relative URL against its base).  The full URL is therefore */
  148. /* <scheme> "://" <net location> <path, always starting with a slash> <additional resource specifiers> */
  149. /* If a given CFURL can be decomposed (that is, conforms to RFC 1808), you can ask for each of the four */
  150. /* basic pieces (scheme, net location, path, and resource specifer) separately, as well as for its base */
  151. /* URL.  The basic pieces are returned with any percent escape sequences still in place (although note */
  152. /* that the scheme may not legally include any percent escapes); this is to allow the caller to distinguish */
  153. /* between percent sequences that may have syntactic meaning if replaced by the character being escaped */
  154. /* (for instance, a '/' in a path component).  Since only the individual schemes know which characters */
  155. /* are syntactically significant, CFURL cannot safely replace any percent escape sequences.  However, */
  156. /* you can use CFStringCreateReplacingPercentEscapes() to create a new string with the percent escapes */
  157. /* removed.  The first argument is the original string containing percent escapes; the second argument */
  158. /* is a string containing any characters that, if escaped in the original string, should NOT be replaced. */
  159. /* Note that this function may return the original string (retained) if the original string contains no */
  160. /* escape sequences to be processed. */
  161. /* If a given CFURL can not be decomposed, you can ask for its scheme and its resource specifier; asking */
  162. /* it for its net location or path will return NULL. */
  163. /* All of the methods discussed above do not require an autorelease pool to be in place. */
  164. /* To get more refined information about the components of a decomposable CFURL, you may ask for more */
  165. /* specific pieces of the URL, expressed with the percent escapes removed.  These functions require an */
  166. /* autorelease pool to be in place, as they will return an autoreleased CFString.  They are */
  167. /* CFURLHostName(), CFURLPortNumber() (actually returns an Int32; does not use the autorelease pool), */
  168. /* CFURLUserName(), CFURLPassword(), CFURLQuery(), CFURLParameters(), and CFURLFragment().  Because the */
  169. /* parameters, query, and fragment of an URL may contain scheme-specific syntaxes, these methods take a */
  170. /* second argument, giving a list of characters which should NOT be replaced if percent escaped.  For */
  171. /* instance, the ftp parameter syntax gives simple key-value pairs as "<key>=<value>;"  Clearly if a key */
  172. /* or value includes either '=' or ';', it must be escaped to avoid corrupting the meaning of the */
  173. /* parameters, so the caller may request the parameter string as */
  174. /* CFStringRef myParams = CFURLParameters(ftpURL, CFSTR("=;%")); */
  175. /* requesting that all percent escape sequences be replaced by the represented characters, except for escaped */
  176. /* '=', '%' or ';' characters.  If you are not interested in any escape sequences being left in, pass NULL for the */
  177. /* second argument. */
  178. /* Returns TRUE if anURL conforms to RFC 1808 */
  179. EXTERN_API_C( Boolean )
  180. CFURLCanBeDecomposed            (CFURLRef                 anURL);
  181.  
  182. /* The next several methods leave any percent escape sequences intact */
  183. EXTERN_API_C( CFStringRef )
  184. CFURLCopyScheme                    (CFURLRef                 anURL);
  185.  
  186. /* NULL if CFURLCanBeDecomposed(anURL) is FALSE */
  187. EXTERN_API_C( CFStringRef )
  188. CFURLCopyNetLocation            (CFURLRef                 anURL);
  189.  
  190. /* NULL if CFURLCanBeDecomposed(anURL) is FALSE; also does not resolve */
  191. /* the URL against its base.  See also CFCreateAbsoluteURL() and */
  192. /* CFStringCreateFileSystemPathFromURL() */
  193. EXTERN_API_C( CFStringRef )
  194. CFURLCopyPath                    (CFURLRef                 anURL);
  195.  
  196. /* Returns whether anURL's path represents a directory */
  197. /* (TRUE returned) or a simple file (FALSE returned) */
  198. EXTERN_API_C( Boolean )
  199. CFURLHasDirectoryPath            (CFURLRef                 anURL);
  200.  
  201. /* Any additional resource specifiers after the path.  For URLs */
  202. /* that cannot be decomposed, this is everything except the scheme itself. */
  203. EXTERN_API_C( CFStringRef )
  204. CFURLCopyResourceSpecifier        (CFURLRef                 anURL);
  205.  
  206. EXTERN_API_C( CFStringRef )
  207. CFURLCopyHostName                (CFURLRef                 anURL);
  208.  
  209. EXTERN_API_C( SInt32 )
  210. CFURLGetPortNumber                (CFURLRef                 anURL);
  211.  
  212. /* Returns -1 if no port number is specified */
  213. EXTERN_API_C( CFStringRef )
  214. CFURLCopyUserName                (CFURLRef                 anURL);
  215.  
  216. EXTERN_API_C( CFStringRef )
  217. CFURLCopyPassword                (CFURLRef                 anURL);
  218.  
  219. /* These remove all percent escape sequences except those for */
  220. /* characters in charactersToLeaveEscaped.  If charactersToLeaveEscaped */
  221. /* is empty (""), all percent escape sequences are replaced by their */
  222. /* corresponding characters.  If charactersToLeaveEscaped is NULL, */
  223. /* then no escape sequences are removed at all */
  224. EXTERN_API_C( CFStringRef )
  225. CFURLCopyParameterString        (CFURLRef                 anURL,
  226.                                  CFStringRef             charactersToLeaveEscaped);
  227.  
  228. EXTERN_API_C( CFStringRef )
  229. CFURLCopyQueryString            (CFURLRef                 anURL,
  230.                                  CFStringRef             charactersToLeaveEscaped);
  231.  
  232. EXTERN_API_C( CFStringRef )
  233. CFURLCopyFragment                (CFURLRef                 anURL,
  234.                                  CFStringRef             charactersToLeaveEscaped);
  235.  
  236. /* Returns a string with any percent escape sequences that do NOT */
  237. /* correspond to characters in charactersToLeaveEscaped with their */
  238. /* equivalent.  Returns NULL on failure (if an invalid percent sequence */
  239. /* is encountered), or the original string itself if no characters need to be replaced. */
  240. EXTERN_API_C( CFStringRef )
  241. CFURLCreateStringByReplacingPercentEscapes (CFAllocatorRef  allocator,
  242.                                  CFStringRef             originalString,
  243.                                  CFStringRef             charactersToLeaveEscaped);
  244.  
  245.  
  246. #if PRAGMA_ENUM_ALWAYSINT
  247.     #pragma enumsalwaysint reset
  248. #elif PRAGMA_ENUM_OPTIONS
  249.     #pragma option enum=reset
  250. #elif defined(PRAGMA_ENUM_PACK__COREFOUNDATION_CFURL__)
  251.     #pragma options(pack_enums)
  252. #endif
  253.  
  254. #if PRAGMA_STRUCT_ALIGN
  255.     #pragma options align=reset
  256. #elif PRAGMA_STRUCT_PACKPUSH
  257.     #pragma pack(pop)
  258. #elif PRAGMA_STRUCT_PACK
  259.     #pragma pack()
  260. #endif
  261.  
  262. #ifdef PRAGMA_IMPORT_OFF
  263. #pragma import off
  264. #elif PRAGMA_IMPORT
  265. #pragma import reset
  266. #endif
  267.  
  268. #ifdef __cplusplus
  269. }
  270. #endif
  271.  
  272. #endif /* __COREFOUNDATION_CFURL__ */
  273.  
  274.